/* -*- Mode: java; indent-tabs-mode: nil; c-basic-offset: 2 -*-
 *
 * The contents of this file are subject to the Mozilla Public
 * License Version 1.1 (the "License"); you may not use this file
 * except in compliance with the License. You may obtain a copy of
 * the License at http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * rights and limitations under the License.
 *
 * The Original Code is the Grendel mail/news client.
 *
 * The Initial Developer of the Original Code is Netscape Communications
 * Corporation.  Portions created by Netscape are
 * Copyright (C) 1997 Netscape Communications Corporation. All
 * Rights Reserved.
 *
 * Contributor(s): Nokia Corporation.
 *
 * Created: Jamie Zawinski <jwz@netscape.com>, 13 Jun 1995.
 * Ported from C on 14 Aug 1997.
 */

/*
 * Modified by Nokia for use in J2ME, MobileNews NNTP client in July 2005.
 * See the IThreadable.java.diff file for changes to the original class.
 */

/**
 This is an interface representing messages to be threaded by references.
 It is the interface to the Threader.

 @see Threader
 @see ISortable
 @see Sorter
 */

package org.minig.threading;


public interface IThreadable {

	/**
	 * Returns an object identifying this message. Generally this will be a
	 * representation of the contents of the Message-ID header. It may be a
	 * String, or it may be something else; the only constraint is that
	 * <TT>equals</TT> and <TT>hashCode</TT> work properly on it. (That is, two
	 * ID objects are equal and hash the same if they represent the same
	 * underlying ID-string.)
	 */
	String getMessageID();

	/**
	 * Returns the IDs of the set of messages referenced by this one. This list
	 * should be ordered from oldest-ancestor to youngest-ancestor. As for the
	 * <TT>messageThreadID</TT> method, the contents of this array may be any
	 * type of object, so long as <TT>equals</TT> and <TT>hashCode</TT> work
	 * properly on them.
	 */
	String[] getReferences();

	/**
	 * When no references are present, subjects will be used to thread together
	 * messages. This method should return a threadable subject: two messages
	 * with the same simplifiedSubject will be considered to belong to the same
	 * thread. This string should not have `Re:' on the front, and may have been
	 * simplified in whatever other ways seem appropriate.
	 * <P>
	 * This is a String of Unicode characters, and should have had any encodings
	 * (such as RFC 2047 charset encodings) removed first.
	 * <P>
	 * If you aren't interested in threading by subject at all, return null.
	 */
	String getSimplifiedSubject();

	/**
	 * Whether the original subject was one that appeared to be a reply (that
	 * is, had a `Re:' or some other indicator.) When threading by subject, this
	 * property is used to tell whether two messages appear to be siblings, or
	 * in a parent/child relationship.
	 */
	boolean subjectIsReply();

	/**
	 * When the proper thread order has been computed, these two methods will be
	 * called on each IThreadable in the chain, to set up the proper tree
	 * structure.
	 */
	void setNext(IThreadable next);

	void setChild(IThreadable kid);

	/**
	 * Creates a dummy parent object.
	 * <P>
	 * With some set of messages, the only way to achieve proper threading is to
	 * introduce an element into the tree which represents messages which are
	 * not present in the set: for example, when two messages share a common
	 * ancestor, but that ancestor is not in the set. This method is used to
	 * make a placeholder for those sorts of ancestors. It should return an
	 * object which is also a IThreadable. The setNext() and setChild() methods
	 * will be used on this placeholder, as either the object or the argument,
	 * just as for other elements of the tree.
	 */
	IThreadable makeDummy();

	/**
	 * This should return true of dummy messages, false otherwise. It is legal
	 * to pass dummy messages in with the list returned by elements(); the
	 * isDummy() method is the mechanism by which they are noted and ignored.
	 */
	boolean isDummy();

	IThreadable getNext();

	IThreadable getChild();
}
